KCFindInternetPassword

KCFindInternetPassword
Header:	Keychain.h		Carbon status:	Under Evaluation

Finds the first Internet password in the default keychain that matches the specified parameters.

OSStatus KCFindInternetPassword (
    StringPtr serverName, 
    StringPtr securityDomain, 
    StringPtr accountName, 
    UInt16 port, 
    OSType protocol, 
    OSType authType, 
    UInt32 maxLength, 
    void *passwordData, 
    UInt32 *actualLength, 
    KCItemRef *item
);

serverName: A pointer to a Pascal string containing the server name. Pass NULL to match any server name.
securityDomain: A pointer to a Pascal string containing the security domain. Pass NULL to match any domain.
accountName: A pointer to a Pascal string containing the account name. Pass NULL to match any account name.
port: The TCP/IP port number. Pass the constant kAnyPort, described in “Default Port Constant”, to match any port.
protocol: The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values. Pass the constant kAnyProtocol, described in “Default Protocol Constant”, to match any protocol.
authType: The authentication scheme used. See “Authentication Type Constants” for a description of possible values. Pass the constant kAnyAuthType, described in “Default Authentication Type Constant”, to match any authentication scheme.
maxLength: The length of the buffer pointed to by passwordData. Pass 0 if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the passwordData parameter.
passwordData: A pointer to a buffer which will hold the returned password data. Before calling KCFindInternetPassword, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass 0 in the maxLength parameter. On return, a pointer to the returned password data.
actualLength: On return, the actual length of the password data that was retrieved. If the buffer pointed to by passwordData is smaller than the actual length of the data, KCFindInternetPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindInternetPassword again.
item: On return, a pointer to a reference to the found item. Pass NULL if you don’t want to obtain this reference.

function result: A result code. The result code errKCNoDefaultKeychain indicates that no default keychain was found. The result code errKCItemNotFound indicates that no matching password item was found. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCFindInternetPassword again.

DISCUSSION

The KCFindInternetPassword function finds the first Internet password item which matches the attributes you provide. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise KCFindInternetPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindInternetPassword again. KCFindInternetPassword optionally returns a reference to the found item.

VERSION NOTES

Available beginning with Keychain Manager 1.0. In Keychain Manager 1.0, the kcfindinternetpassword function provides the same functionality as KCFindInternetPassword, except that it accepts C strings rather than Pascal strings as arguments. In Keychain 2.0, you should use KCFindInternetPassword, since kcfindinternetpassword is provided for convenience only and may be removed from the header file at some point in the future.

AVAILABILITY

Under evaluation for Carbon. Available in CarbonLib 1.0 and later when KeychainLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by KeychainLib 1.0 and later.